home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 9 / Night Owl CD-ROM (NOPV9) (Night Owl Publisher) (1993).ISO / 001a / seyon213.tz / seyon213 / seyon / MultiList.h < prev    next >
C/C++ Source or Header  |  1993-02-25  |  12KB  |  305 lines
  1.  
  2.  
  3. /****************************************************************************
  4.  
  5.     MultiList.h
  6.  
  7.     This file is the public header file for the MultiList widget, an
  8.     extension to the Athena List widget.
  9.  
  10.     This code is loosely based on the Athena List source which
  11.     is why the MIT copyright notice appears below.
  12.  
  13.     July 1990, Brian Totty
  14.  
  15.  ****************************************************************************/
  16.  
  17. /*
  18.  * Copyright 1989 Massachusetts Institute of Technology
  19.  *
  20.  * Permission to use, copy, modify, distribute, and sell this software and its
  21.  * documentation for any purpose is hereby granted without fee, provided that
  22.  * the above copyright notice appear in all copies and that both that
  23.  * copyright notice and this permission notice appear in supporting
  24.  * documentation, and that the name of M.I.T. not be used in advertising or
  25.  * publicity pertaining to distribution of the software without specific,
  26.  * written prior permission.  M.I.T. makes no representations about the
  27.  * suitability of this software for any purpose.  It is provided "as is"
  28.  * without express or implied warranty.
  29.  *
  30.  * M.I.T. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
  31.  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL M.I.T.
  32.  * BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  33.  * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
  34.  * OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
  35.  * CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  36.  *
  37.  * Original Athena Author:  Chris D. Peterson, MIT X Consortium
  38.  */
  39.  
  40. #ifndef _MULTILIST_H_
  41. #define _MULTILIST_H_
  42.  
  43. #include <X11/Xaw/Simple.h>
  44.  
  45. /*---------------------------------------------------------------------------*
  46.  
  47.       R E S O U R C E    D E S C R I P T I O N S    A N D    N O T E S
  48.  
  49.  *---------------------------------------------------------------------------*/
  50.  
  51. /*
  52.  
  53.  Name             Class        RepType        Default Value
  54.  ----             -----        -------        -------------
  55.  background         Background        Pixel        XtDefaultBackground
  56.  border             BorderColor    Pixel        XtDefaultForeground
  57.  borderWidth         BorderWidth    Dimension    1
  58.  callback            Callback           XtCallbackList  NULL                *1
  59.  columnWidth         Width              Dimension       0                   *10
  60.  columnSpacing       Spacing            Dimension       8
  61.  cursor             Cursor        Cursor        left_ptr
  62.  defaultColumns      Columns            int             1                   *2
  63.  destroyCallback     Callback        Pointer        NULL
  64.  font             Font        XFontStruct*    XtDefaultFont
  65.  forceColumns        Columns            Boolean         False               *2
  66.  foreground         Foreground        Pixel        XtDefaultForeground
  67.  height             Height        Dimension    0                   *3
  68.  highlightBackground HBackground    Pixel        XtDefaultForeground *4
  69.  highlightForeground HForeground    Pixel        XtDefaultBackground *4
  70.  insensitiveBorder   Insensitive    Pixmap        Gray
  71.  list                List               String *        NULL                *5
  72.  longest             Longest            int             0                   *6
  73.  mappedWhenManaged   MappedWhenManaged    Boolean        True
  74.  maxSelectable       Value              int             1                   *7
  75.  notifyHighlights    Boolean            Boolean         True                *8
  76.  notifyOpens         Boolean            Boolean         True                *8
  77.  notifyUnhighlights  Boolean            Boolean         True                *8
  78.  numberStrings       NumberStrings      int             0                   *5
  79.  pasteBuffer         Boolean            Boolean         False
  80.  rowHeight           Height             Dimension       0                   *10
  81.  rowSpacing          Spacing            Dimension       2
  82.  sensitive         Sensitive        Boolean        True
  83.  sensitiveArray      List               Boolean *       NULL                *9
  84.  shadeSurplus         Boolean        Boolean        True            *11
  85.  verticalList        Boolean            Boolean         False
  86.  width             Width        Dimension    0
  87.  x             Position        Position    0
  88.  y             Position        Position    0
  89.  
  90.  *1 -  The callback functions are called whenever a highlight, unhighlight,
  91.        or open takes place, and the appropriate notification resource is
  92.        set true.  The callbacks get called with a MultiListReturnStruct pointer
  93.        which points to the data about the action that just occurred.
  94.  
  95.  *2 -  The defaultColumns resource is used in two cases.  If forceColumns
  96.        is true, the widget will set the number of columns to the value of
  97.        default columns.  If the widget width is unconstrained by the parent
  98.        widgets, the defaultColumns is also used to determine the number of
  99.        columns and the resulting width.  Otherwise, the number of columns
  100.        will be calcultaed based on the current width and will be changed to
  101.        an appropriate value.
  102.  
  103.  *3 -  If the width or height is set to zero (0), which is the default case,
  104.        then the widget will calculate the size of that dimension to be just
  105.        large enough to hold the contents of the widget.
  106.  
  107.  *4 -  The highlightForeground and highlightBackground colors specify the
  108.        colors used to highlight the text (foreground) and the surrounding
  109.        background space of a list item when it is selected (highlighted).
  110.        The default is the reverse of the default foreground and background
  111.        colors.
  112.  
  113.  *5 -  The list resource is an array of strings (char * array) which tell
  114.        the names of each item of the list.  The number of elements of this
  115.        array are indicated by the resource numberStrings.  If numberStrings
  116.        is set to 0 (the default), then the MultiList widget will count the
  117.        number of strings in the list.  This requires that the list be
  118.        NULL terminated.  If list is NULL, then the widget treats it as an
  119.        empty list.  Once the list is set the list resource is set to NULL,
  120.        so you won't be able to read back the list after it has been set.  The
  121.        widgets copies the strings internally, so the user can free the list
  122.        storage after setting it.
  123.  
  124.  *6 -  This resource represent the longest string in pixels.  If this
  125.        resource is zero (0), which is the default and probably the value
  126.        most people should use, the longest string length is calculated
  127.        and the resource is updated.
  128.  
  129.  *7 -  The maxSelectable resource indicates the maximum number of items
  130.        which can be selected at any one time.  In the original Athena
  131.        widget, you could have at most one item selected at a time.  In
  132.        this widget, you can choose how many will be selected at a time.
  133.  
  134.  *8 -  When an item is highlighted or becomes unhighlighted, or when
  135.        the Open() action is run, a callback can be issued indicating the
  136.        new state of what items are highlighted and what action occurred.
  137.        The notify resources are booleans that enable or disable callbacks
  138.        in various cases.  If you are only interested in being notified
  139.        when the user selects an item, and not when he deselects items,
  140.        then only notifyHighlights needs to be True.
  141.  
  142.  *9 -  Each item in the MultiList can be made insensitive, so it is printed in
  143.        gray shading and can not be highlighted.  This can be done by
  144.        setting the sensitivity list, which is an array of Booleans which
  145.        indicate whether or not the corresponding item is sensitive (can be
  146.        selected).  If sensitivity list is NULL, all items are sensitive.  The
  147.        widget copies the sensitivity information, so the user can delete the
  148.        sensitivity array storage after setting it.  The widget sets the
  149.        resource to NULL after it has been set, so the user cannot read the
  150.        old list back.
  151.  
  152.  *10 - These values are intended for reading only.  They indicate the pixel
  153.        width/height of the column/row.
  154.  
  155.  *11 - If the list height is made larger than the sum of the list entry
  156.        heights, the surplus space is shaded in the background color if
  157.        shadeSurplus is False, or in a gray stipple pattern if shadeSurplus
  158.        is True.
  159.  
  160. */
  161.  
  162. /*---------------------------------------------------------------------------*
  163.  
  164.                     S T R I N G    D E F I N I T I O N S
  165.  
  166.  *---------------------------------------------------------------------------*/
  167.  
  168. #ifndef XtCList
  169. #define XtCList            "List"
  170. #endif
  171.  
  172. #ifndef XtCSpacing
  173. #define XtCSpacing        "Spacing"
  174. #endif
  175.  
  176. #ifndef XtCColumns
  177. #define XtCColumns        "Columns"
  178. #endif
  179.  
  180. #ifndef XtCLongest
  181. #define XtCLongest        "Longest"
  182. #endif
  183.  
  184. #define XtCNumberStrings    "NumberStrings"
  185. #define    XtCHForeground        "HForeground"
  186. #define    XtCHBackground        "HBackground"
  187.  
  188. #ifndef XtNcursor
  189. #define XtNcursor        "cursor"
  190. #endif
  191.  
  192. #define    XtNhighlightForeground    "highlightForeground"
  193. #define    XtNhighlightBackground    "highlightBackground"
  194. #define XtNcolumnSpacing    "columnSpacing"
  195.  
  196. #ifndef XtNrowSpacing
  197. #define XtNrowSpacing        "rowSpacing"
  198. #endif
  199.  
  200. #define XtNdefaultColumns    "defaultColumns"
  201.  
  202. #ifndef XtNforceColumns
  203. #define XtNforceColumns        "forceColumns"
  204. #endif
  205.  
  206. #ifndef XtNpasteBuffer
  207. #define XtNpasteBuffer        "pasteBuffer"
  208. #endif
  209.  
  210. #ifndef XtNverticalList
  211. #define XtNverticalList        "verticalList"
  212. #endif
  213.  
  214. #ifndef XtNlongest
  215. #define XtNlongest        "longest"
  216. #endif
  217.  
  218. #define XtNnumberStrings    "numberStrings"
  219.  
  220. #ifndef XtNlist
  221. #define XtNlist            "list"
  222. #endif
  223.  
  224. #define    XtNsensitiveArray    "sensitiveArray"
  225. #define    XtNmaxSelectable    "maxSelectable"
  226. #define    XtNnotifyHighlights    "notifyHighlights"
  227. #define    XtNnotifyUnhighlights    "notifyUnhighlights"
  228. #define    XtNnotifyOpens        "notifyOpens"
  229. #define    XtNshadeSurplus        "shadeSurplus"
  230.  
  231. #define    XtNrowHeight        "rowHeight"
  232. #define    XtNcolumnWidth        "columnWidth"
  233.  
  234.  /* Class Record Constants */
  235.  
  236. extern WidgetClass xfwfMultiListWidgetClass;
  237.  
  238. typedef struct _XfwfMultiListClassRec *XfwfMultiListWidgetClass;
  239. typedef struct _XfwfMultiListRec *XfwfMultiListWidget;
  240.  
  241. /*---------------------------------------------------------------------------*
  242.  
  243.                      R E T U R N    S T R U C T U R E
  244.  
  245.  *---------------------------------------------------------------------------*/
  246.  
  247. #define    XfwfMultiListActionNothing        0
  248. #define    XfwfMultiListActionHighlight        1
  249. #define    XfwfMultiListActionUnhighlight        2
  250. #define    XfwfMultiListActionOpen            3
  251. #define    XfwfMultiListActionStatus        4
  252.  
  253. typedef struct _XfwfMultiListReturnStruct {
  254.   int             action;
  255.   int             item;
  256.   String          string;
  257.   int             num_selected;
  258.   int            *selected_items;
  259. }
  260.  
  261. XfwfMultiListReturnStruct;
  262.  
  263. /*---------------------------------------------------------------------------*
  264.  
  265.                      U T I L I T Y    R O U T I N E S
  266.  
  267.  *---------------------------------------------------------------------------*/
  268.  
  269. #if (!NeedFunctionPrototypes)
  270.  
  271. extern Boolean  XfwfMultiListHighlightItem();
  272. extern void     XfwfMultiListHighlightAll();
  273. extern void     XfwfMultiListUnhighlightItem();
  274. extern void     XfwfMultiListUnhighlightAll();
  275. extern int      XfwfMultiListToggleItem();
  276. extern XfwfMultiListReturnStruct *
  277.                 XfwfMultiListGetHighlighted();
  278. extern Boolean  XfwfMultiListIsHighlighted();
  279. extern Boolean  XfwfMultiListGetItemInfo();
  280. extern void     XfwfMultiListSetNewData();
  281.  
  282. #else
  283.  
  284. extern Boolean  XfwfMultiListHighlightItem(XfwfMultiListWidget mlw,
  285.                        int item_index);
  286. extern void     XfwfMultiListHighlightAll(XfwfMultiListWidget mlw);
  287. extern void     XfwfMultiListUnhighlightItem(XfwfMultiListWidget mlw,
  288.                          int item_index);
  289. extern void     XfwfMultiListUnhighlightAll(XfwfMultiListWidget mlw);
  290. extern int      XfwfMultiListToggleItem(XfwfMultiListWidget mlw,
  291.                     int item_index);
  292. extern XfwfMultiListReturnStruct *
  293.                 XfwfMultiListGetHighlighted(XfwfMultiListWidget mlw);
  294. extern Boolean  XfwfMultiListIsHighlighted(XfwfMultiListWidget mlw,
  295.                        int item_index);
  296. extern Boolean  XfwfMultiListGetItemInfo(XfwfMultiListWidget mlw,
  297.                      int item_index, String * str_ptr,
  298.                      Boolean * h_ptr, Boolean * s_ptr);
  299. extern void     XfwfMultiListSetNewData(XfwfMultiListWidget mlw,
  300.                      String * list, int nitems, int longest,
  301.                    int resize, Boolean * sensitivity_array);
  302.  
  303. #endif
  304. #endif
  305.